home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / programr / catch.zip / INSTRUCT.DOC < prev    next >
Text File  |  1993-03-03  |  19KB  |  866 lines

  1.  
  2. This file contains the following sections :
  3.  
  4.         Section 1 :     Description of commands, flags, etc
  5.         Section 2 :     Help and suggestions
  6.  
  7.  
  8.                                SECTION 1
  9.                                =========
  10.  
  11. @CANCEL
  12. -------
  13. This flag is set if a user selects Cancel from a FILESELECT box.
  14.  
  15.  
  16.  
  17. @ENHANCED
  18. ---------
  19. This flag is set if Windows is running in enhanced mode.
  20.  
  21. See also @REAL and @STANDARD
  22.  
  23.  
  24.  
  25. @EXISTS
  26. -------
  27. This flag is set if a window was found with the EXISTS function.
  28.  
  29. See also @NOEXISTS
  30.  
  31.  
  32.  
  33. @FILE
  34. -----
  35.  
  36. This flag is set if a file was found with the FINDFILE function.
  37.  
  38.  
  39.  
  40. @FIND
  41. -----
  42.  
  43. This flag is set if a string was found with the FINDSTRING function.
  44.  
  45.  
  46. @ICON
  47. -----
  48.  
  49. This flag is set if a window was found to be minimized with the ISICON function.
  50.  
  51. See also @MAX
  52.  
  53.  
  54.  
  55. @MAX
  56. ----
  57.  
  58. This flag is set if a window was found to be maximized with the ISMAX function.
  59.  
  60. See also @ICON
  61.  
  62.  
  63.  
  64. @NO
  65. ---
  66.  
  67. This flag is set if a user selects No from an ASK box.
  68.  
  69. See also @YES
  70.  
  71.  
  72.  
  73. @NOEXISTS
  74. ---------
  75.  
  76. This flag is set if a window was not found with the EXISTS function.
  77.  
  78. See also @EXISTS
  79.  
  80.  
  81.  
  82. @QUERY
  83. ------
  84.  
  85.  
  86. This flag is set if a user entered text using the INPUT function.
  87.  
  88.  
  89.  
  90. @REAL
  91. -----
  92.  
  93. This flag is set if Windows is running in real mode
  94.  
  95. See also @STANDARD and @ENHANCED
  96.  
  97.  
  98.  
  99. @SELECT
  100.  
  101. This flag is set if a user selects a file with the FILESELECT function.
  102.  
  103.  
  104.  
  105. @STANDARD
  106. ---------
  107.  
  108. This flag is set if Windows is running in standard mode.
  109.  
  110. See also @REAL and @ENHANCED
  111.  
  112.  
  113.  
  114. @VER30
  115. ------
  116.  
  117. This flag is set if the user is running Windows 3.0
  118.  
  119. See also @VER31
  120.  
  121.  
  122. @VER31
  123. ------
  124.  
  125. This flag is set if the user is running Windows 3.1
  126.  
  127. See also @VER30
  128.  
  129.  
  130.  
  131. @YES
  132. ----
  133.  
  134. This flag is set if a user selects Yes from an ASK box
  135.  
  136. See also @NO
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146. About()
  147. -------
  148.  
  149. This function simply displays the cresits for Catch
  150.  
  151.  
  152. Additem (item)
  153. --------------
  154.  
  155. This function add the string specified by 'item' to the choice box. The
  156. choice box can hold a maximum of 30 items. To select an item use the
  157. CHOICE function.
  158.  
  159.  
  160. Ask (caption, message)
  161. ----------------------
  162.  
  163. This function displays the string 'caption' in the caption bar of the ASK box,
  164. and the string in 'message' in the center of the message box. It then prompts
  165. the user to select either YES or NO.
  166.  
  167. Returns : YES if Yes was selected, NO if No was selected.
  168.  
  169. This function also sets the @YES or @NO flags, depending on which choice the
  170. user makes.
  171.  
  172. EG :    Ask ("Click", "Click either Yes or No")
  173.     If @YES Ok ("","You clicked Yes")
  174.     If @NO Ok ("","You clicked No")
  175.  
  176.  
  177.  
  178. Comparitors
  179. -----------
  180. Catch provides 6 comparitors which allow you to compare strings. They are:
  181.  
  182. 1. ==    Equals
  183. 2. <>    Is not equal to
  184. 3. >=     Greater than or equal to
  185. 4. <=    Less than or equal to
  186. 5. >    Greater than
  187. 6. <    Less than
  188.  
  189.  
  190.  
  191. Cd (pathname)
  192. -------------
  193.  
  194. This functio allows you to change directory
  195.  
  196.  
  197. ChDir (pathname)
  198. ----------------
  199.  
  200. See CD for a full description
  201.  
  202.  
  203.  
  204. Choice (caption, message)
  205. -------------------------
  206.  
  207. This function allows you to choose one of the items added to the choice box
  208. with the ADDITEM command. The text specified by 'caption' is displayed in the
  209. window caption bar and the text specifed by 'message' is displayed in the
  210. window.
  211.  
  212. Returns : The selected item if one is chosen, otherwise an empty string.
  213.  
  214.  
  215. Close (partial window name)
  216. ---------------------------
  217.  
  218. This function terminates (closes) the program specified by 'partial window
  219. name'.
  220.  
  221. For a full description of window names see the section "Windows names".
  222.  
  223.  
  224. Del (filespec)
  225. --------------
  226. This function allows you to delete one or more files specified by 'filespec'.
  227. To delete a file specify its filename. To delete multiple filenames you may
  228. use wildcards.
  229.  
  230.  
  231.  
  232. Exists (partial window name)
  233. ----------------------------
  234. This function checks to see if the program specified by 'partial window name'
  235. is running.
  236.  
  237. It returns TRUE if the window exists, FALSE otherwise.
  238.  
  239. This function also sets the @EXISTS flag if the window exists and the @NOEXISTS flag if the window does not exist.
  240.  
  241. See the section "Window names" for details on how to specify Windows names.
  242.  
  243. EG :    Exists ("Program Manager")
  244.     If @EXISTS ok ("" "Program manager is running")
  245.  
  246.     Let running=Exists ("Clock")
  247.     if running=="FALSE" runmin ("clock.exe","")
  248.  
  249.  
  250.  
  251. FileSelect (filespec)
  252. ---------------------
  253.  
  254. This function allows you to give the user a choice of files to pick from.
  255.  
  256. Returns : Returns the name of selected file if one is selected, otherwise an
  257. empty string.
  258.  
  259. EG :    Let file=FileSelect("c:\windows\*.exe")
  260.     RunMin (file,"")
  261.  
  262.     Let path="c:\temp\*.*"
  263.     FileSelect(path)
  264.  
  265.  
  266. FindFile (filename)
  267. -------------------
  268.  
  269. This function looks to see if the file specified by 'filename' exists.
  270.  
  271. 'filename' may also include a directory specifier.
  272.  
  273. Returns : The full filename (path + filename) of the file, otherwise an empty
  274. string.
  275.  
  276. This function alters the @FILE flag.
  277.  
  278. See the section "Search order" for details on where Catch looks for files.
  279.  
  280. Example
  281. =======
  282.  
  283. This example checks to see if the Windows file README.TXT file exists in the directory C:\WINDOWS
  284.  
  285. Let name=FindFile ("c:\windows\readme.txt")
  286. If @FILE Ok ("","Found README.TXT")
  287.  
  288. This examples searches the directories specified in the section "Search order" for the file WIN.COM
  289.  
  290. Let name=FindFile("win.com")
  291. If @FILE Ok ("","Found WIN.COM")
  292.  
  293.  
  294. FindString (filename, string)
  295. -----------------------------
  296.  
  297. This function searches the file specified by 'filename' for the string
  298. specified by 'string'.
  299.  
  300. Returns : The filename if successful, otherwise an empty string.
  301.  
  302.  
  303.  
  304. Flags
  305. -----
  306. Catch has a series of pre-defined flags which are set to either TRUE of FALSE,
  307. depending oncertian actions.
  308.  
  309. These flags can be used used in IF statements to test to see if certain actions
  310. have taken place.
  311.  
  312.  
  313.  
  314. GetCatchDir()
  315. -------------
  316.  
  317. This function returns the directory name in which Catch is stored. The
  318. returned string includes the drive specifier but does not end in a backslash
  319. (\).
  320.  
  321. Example
  322. =======
  323.  
  324. If Catch is on the C: drive in a directory called CATCH then this example will
  325. display C:\CATCH
  326.  
  327. Let dir=GetCatchDir()
  328. Ok ("Catch", dir)
  329.  
  330.  
  331. GetEnv (varname)
  332. ----------------
  333.  
  334. This function returns the value of the environmental variable pointed to by
  335. 'varname'.
  336.  
  337. Returns : The value of the variable if it exists, otherwise an empty string
  338.  
  339. Example
  340. =======
  341.  
  342. To get the PATH setting
  343.  
  344. Let path=GetEnv("path")
  345.  
  346.  
  347.  
  348. GetFreeMem()
  349. ------------
  350.  
  351. This function returns the amount of free memory available in K
  352.  
  353.  
  354.  
  355. GetIniData (appname, keyname, default, file)
  356. --------------------------------------------
  357.  
  358. This function looks in a .INI file specified by 'file' for the value held by
  359. 'keyname' uder the section 'appname'.
  360.  
  361. If 'appname' or 'keyname' do not exists then you can specify a default value
  362. in the 'defualt' string.
  363.  
  364. See the section ".INI" for more details on .INI files.
  365.  
  366. Returns : The required value if it exists, otherwise the value held in
  367. 'default'.
  368.  
  369.  
  370.  
  371. GetSysDir()
  372. -----------
  373. This function returns the Windows system directory. This directory contains
  374. Windows fonts, libraries and drivers.
  375.  
  376. The retrieved pathname does not end with a backslash (\).
  377.  
  378. Example
  379. =======
  380.  
  381. If the system directory is named WINDOWS\SYSTEM and is on drive C: then the
  382. following example will display C:\WINDOWS\SYSTEM
  383.  
  384. Let dir=GetSysDir()
  385. Ok ("",dir)
  386.  
  387.  
  388. GetWinDir()
  389. -----------
  390.  
  391. This function returns the directory in which Windows is installed. This is the
  392. directory which typically holds the file WIN.COM.
  393.  
  394. The string returned does not end with a backslash (\) unless Windows is
  395. installed in the root directory.
  396.  
  397. Example
  398. =======
  399.  
  400. If Windows is installed in the directory WINDOWS on the C: drive then the
  401. following example will display C:\WINDOWS
  402.  
  403. Let dir=GetWinDir()
  404. Ok ("", dir)
  405.  
  406.  
  407. Goto label
  408. ----------
  409.  
  410. This function advances execution to the line after 'label'.
  411.  
  412. EG :    Goto load
  413.     .........
  414.     .........
  415.     .........
  416.     :load
  417.     Ok ("", "Skipped")
  418.  
  419. See the section on labels for details on how to specify labels
  420.  
  421.  
  422.  
  423. If
  424. --
  425.  
  426. If flag dotrue | dofalse
  427. If string1 <comparitor> string2 dotrue | dofalse
  428.  
  429. The If function allows you to carry out functions depending on whether of not
  430. a flag or comparison evaluates to TRUE.
  431.  
  432. In the first case, 'flag' is a pre-defined flag which is set to either TRUE or
  433. FALSE. A flag CANNOT be compared with another value.
  434.  
  435. Example
  436. =======
  437.  
  438. This function displays a message if the version of Windows running is 3.0
  439.  
  440.         If @VER30 Ok ("Windows", "This is Windows 3.0")
  441.  
  442.  
  443. In the second case you can compare 2 strings. The comparison compares 'string1' to 'string2' and evaluates to either TRUE or FALSE.
  444.  
  445. To see a list of available comparitors see the section "Comparitors"
  446.  
  447. Example
  448. =======
  449.  
  450. This function checks to make sure a correct password has been typed.
  451.  
  452.         Let password=Input("Password", "Enter password")
  453.         If password<>"BLUE" ok ("Password", "Invalid password")
  454.  
  455.  
  456. You can include an ELSE clause which will be carried out if the flag or string comparison evaluates to FALSE. An ELSE clause is included by seperating the 2 functions to be carried out with a vertical bar (|).
  457.  
  458. Example
  459. =======
  460.  
  461. If @VER30 Ok ("Windows", "Windows 3.0") | Ok ("Windows", "Windows 3.1")
  462.  
  463.  
  464.  
  465. .INI
  466. ----
  467. .INI files have the following layout :
  468.  
  469. [appname]
  470. keyname=value
  471.  
  472. You can obtain information fron a .INI file by using GETINIDATA.
  473. You can write data to, and delete data from a .INI file using WRITEINIDATA.
  474.  
  475.  
  476.  
  477. Input (caption, message)
  478. ------------------------
  479.  
  480. This function allow you to let the user enter data.
  481.  
  482. The text specified by 'caption' is displayed in the windows caption bar and the
  483. string specified by message is displayed in the window.
  484.  
  485. Returns : This function returns the text entered by the user.
  486.  
  487. Example
  488. =======
  489.  
  490. Let params=Input ("Load Notepad", "Enter file to load")
  491. RunMin ("notepad.exe", params)
  492.  
  493.  
  494.  
  495. IsIcon (partial window name)
  496. ----------------------------
  497.  
  498. This function returns TRUE if the window specified by 'partial window name' is
  499. an icon, FALSE otherwise.
  500.  
  501. IsIcon also sets the @ICON flag if the window is an icon.
  502.  
  503. See "Window names" for more info on how to specify a window name.
  504.  
  505.  
  506.  
  507. IsMax (partial window name)
  508. ---------------------------
  509.  
  510. This function checks to see if the window specified by 'partial window name'
  511. is currently maximized.
  512.  
  513. Returns : TRUE if the window is maximized, FALSE otherwise.
  514.  
  515. This function also sets the @MAX flag if the window is maximized.
  516.  
  517.  
  518.  
  519. Join (string1, string2)
  520. -----------------------
  521.  
  522. This function returns the result of appending 'string2' to 'string1'. Both
  523. 'string1' and 'string2' are unchanged.
  524.  
  525. Example
  526. =======
  527.  
  528. Let s1="Hello"
  529. Let s1=" there"
  530. Let s3=Join (s1,s2)
  531.  
  532. s2 how contains "Hello there"
  533.  
  534.  
  535. Let
  536. ---
  537.  
  538. Let varname=string
  539. Let varname=function
  540.  
  541. Let assigns either the text in 'string' if a string is specified to 'varname',
  542. of the return string from the function specified by 'function'.
  543.  
  544. If 'varname' already exists then the previous contents is owerwritten.
  545.  
  546. Example
  547. =======
  548.  
  549. Let message="Do you want to load Clock"
  550. Let file=FindString("readme.txt", "Procedures")
  551.  
  552.  
  553. Max
  554. ---
  555.  
  556. Max (partial window name)
  557. Maximize (partial window name)
  558.  
  559. This function maximizes a window to its full size.
  560.  
  561. For details on how to specify a window name see the section "Window names"
  562.  
  563. EG :    Max ("Write")
  564.  
  565.  
  566. Mem()
  567. -----
  568. This function displays a dialog box showing the following details :
  569.  
  570. 1. Which processor is present.
  571. 2. The mode Windows is running in.
  572. 3. The amount of free memory available
  573.  
  574.  
  575. Min
  576. ---
  577.  
  578. Min (partial window name)
  579. Mimimize (partial window name)
  580.  
  581. This function allows you to minimize (iconise) a window by specifying its name.
  582. The full name of the window does not need to be specified. For example, to
  583. minimize Notepad when it is editing README.DOC you could use :
  584.  
  585.     Min ("notepad")
  586. or    Min ("notepad - README")
  587.  
  588. Case is NOT important when specifying a window name.
  589.  
  590. See the section "Window names" for more info.
  591.  
  592.  
  593. MkDir (dirname)
  594. ---------------
  595.  
  596. This function creates the direcory specified by 'dirname'.
  597.  
  598. An error occurs if the direcory already exists or if the pathname is invalid.
  599.  
  600. Example
  601. =======
  602.  
  603. MkDir ("temp")
  604.  
  605.  
  606. Move (partial window name, x1, y1, x2, y2)
  607. ------------------------------------------
  608.  
  609. This function moves and resizes the window specified by 'partial window name'
  610. so that its top left corner is in position x1,y1 and it is x2 pixels wide
  611. and y2 pixel high.
  612.  
  613. The coordinates x1, y1, x2, y2 must be specified as numbers. They CANNOT be
  614. variables.
  615.  
  616. See the section "Window names" for details on how to specify window names.
  617.  
  618. EG :    Move ("Program Manager",1,1,100,100)
  619.  
  620.  
  621.  
  622. Ok (caption, message)
  623. ---------------------
  624.  
  625. This function displays the string 'caption' in the caption bar of the ASK box,
  626. and the string in 'message' in the center of the message box. It then waits for
  627. the user to click on Ok
  628.  
  629. EG :    Ok ("Notepad", "Click to load Notepad")
  630.  
  631.  
  632. Rename (oldfile, newfile)
  633. -------------------------
  634.  
  635. This function renames the program specified by 'oldfile' to the name specified
  636. by 'newfile'.
  637.  
  638. If the old and new file names are in different directories then this function
  639. copies the file in 'oldfile' to the directory specified in 'newfile' and
  640. changes the name to that specified by 'newfile'.
  641.  
  642. EG :    Rename ("readme.doc", "readme.txt")
  643.  
  644. To copy:
  645.  
  646.     Rename ("readme.doc", "c:\temp\readme.doc")
  647.     Copies README.DOC to directory C:\TEMP and changes the filename to README.DOC
  648.  
  649.  
  650.  
  651. Restore
  652. -------
  653.  
  654. Rst (partial window name)
  655. Restore (partial window name)
  656.  
  657. This function restores a window to it previous size prior to a minimize or
  658. maximize command.
  659.  
  660. See the section "Window names" for details on how to specify a window name.
  661.  
  662. EG :    Rst ("notepad")
  663.  
  664.     Let name="clock"
  665.     Rst (clock)
  666.  
  667.  
  668.  
  669.  
  670. RmDir (dirname)
  671. ---------------
  672.  
  673. This function removes the directory specified by 'dirname'.
  674.  
  675. An error occurs if the directory is not empty or if the directory does not
  676. exist.
  677.  
  678. Example
  679. =======
  680.  
  681. RmDir ("temp")
  682.  
  683.  
  684.  
  685. Run (filename, parameters)
  686. --------------------------
  687.  
  688. This function runs the program specified by 'filename' and passes to it any
  689. parameters specified by 'parameters'.
  690.  
  691. EG :    Run ("clock", "")
  692.         Run ("notepad", "readme.doc")
  693.  
  694.  
  695.  
  696. RunMax (filename, parameters)
  697. -----------------------------
  698.  
  699. This function runs the program specified by 'filename' as a maximized window
  700. and passes to it any parameters specified by 'parameters'.
  701.  
  702. EG :    RunMax ("clock", "")
  703.     RunMax ("notepad", "readme.doc")
  704.  
  705.  
  706.  
  707. RunMin (filename, parameters)
  708. -----------------------------
  709.  
  710. This function runs the program specified by 'filename' as an icon and passes
  711. to it any parameters specified by 'parameters'.
  712.  
  713. EG :    RunMin ("clock", "")
  714.     RunMin ("notepad", "readme.doc")
  715.  
  716.  
  717.  
  718.  
  719. Search order
  720. ------------
  721.  
  722. Whenever you use a command which access a program of file, such as RUN and
  723. FINDSTRING, and do not specify a path, Windows will search the following
  724. directories in the given order:
  725.  
  726.         1. The current directory
  727.         2. The Windows directory (obtainable by using GETWINDIR)
  728.         3. The Windows system directory (obtainable by using GETSYSDIR)
  729.         4. The directories listed in the PATH environmental variable
  730.         5. The list of directories mapped in a network
  731.  
  732.  
  733.  
  734. SendToClipboard (filename)
  735. --------------------------
  736.  
  737. This function sends the text in the file 'filename' to the clipboard.
  738.  
  739. An error occurs if the file does not exist.
  740.  
  741. The file must not be larger than 64K (65536 bytes).
  742.  
  743. Example
  744. =======
  745.  
  746. This function send the file README.TXT to the clipboard
  747.  
  748. SendToClipboard ("README.TXT")
  749.  
  750.  
  751. Upper (var)
  752. -----------
  753.  
  754. This function returns the result of converting all the alphabetic characters
  755. in 'var' to uppercase. 'var' is left unchanged.
  756.  
  757. Example
  758. =======
  759.  
  760. This example sets 'name' to HELLO
  761.  
  762. Let name=Upper ("hello")
  763.  
  764. This example set 'name' to YES
  765.  
  766. Let message="yes"
  767. Let name=Upper(message)
  768.  
  769.  
  770.  
  771. UseLib (libname)
  772. ----------------
  773.  
  774. This function allows you to use third party functions which have been specially
  775. designed for use with Catch.
  776.  
  777. The 'libname' must be the name of a .DLL (Dynamic Link Library).
  778.  
  779. Once you have accessed the .DLL using USELIB you canuse the functions in it as
  780. you would any other Catch function.
  781.  
  782. Example
  783. =======
  784.  
  785. If the library CATCH.DLL contains a function called Lower which converts a string to lower case then you can use it in the following way:
  786.  
  787. UseLib ("catch.dll")
  788. Let name=Lower("FRED")
  789.  
  790.  
  791. This will store 'fred' in the variable 'name'
  792.  
  793. For information on how to write Catch libraries see the file README.DOC
  794.  
  795.  
  796. Variable names
  797. --------------
  798. Variable names in Catch can consist of alphabetic characters only. Numeric
  799. and punctuation characters are not allowed. For example:
  800.  
  801.         filename        is valid
  802.         file1           is not
  803.  
  804.         name            is valid
  805.         _name           is not
  806.  
  807.  
  808.  
  809. Window names
  810. ------------
  811.  
  812. Windows identifies a window by the text in its caption bar (The text between
  813. the system menu box and the minimize icon).
  814.  
  815. For example, when you load up Notepad without a file the caption bar reads
  816. "Notepad - (untitled)".
  817.  
  818. The problem with this is that if you change the file's name to say "README.DOC"
  819.  the caption bar changes to "Notepad - README.DOC"
  820.  
  821. In order to prevent you from having to allow for these changes in a window's
  822. name Catch allows you to specify partial window names. This means that you
  823. DO NOT have to specify the whole name.
  824.  
  825. For example, to maximize Notepad, no matter which file it is editing use the
  826. command:
  827.  
  828.         Max ("notepad")
  829.  
  830.  
  831.  
  832.  
  833. WriteIniData (appname, key, value, file)
  834. ----------------------------------------
  835.  
  836. This function write the value specified by 'value to the .INI file specified by
  837. 'file'. The value is placed under the section 'appname' and is assigned to the
  838. keyname 'keyname'.
  839.  
  840. To remove a keyname set 'value' to an empty string (""). To remove an entire
  841. application section set 'appname' to an empty string.
  842.  
  843. See the section ".INI" for a full explanation on .INI files.
  844.  
  845.  
  846.  
  847.  
  848.                                SECTION 2
  849.                                =========
  850.  
  851. Thank you for trying Catch, I hope it has managed to fill all of your
  852. requirements. If you have any hints or suggestions then write to me at :
  853.  
  854.         Sean Batten
  855.         112 Grand Avenue
  856.         Berrylands
  857.         Surbiton
  858.         Kingston Upon Thames
  859.         England
  860.         KT5 9JA
  861.  
  862. Alternativly you can send email to :
  863.  
  864.         cs_e404@kingston.ac.uk
  865.  
  866.